DELPHI IDE Pathes - Felix John COLIBRI.

• abstract : How to include a Unit for compilation, loading in the Editor or debugging: the Windows environment PATH, the RSVARS.BAT $(BDS), the Registry pathes, the "Tools | Environment | Library" and "Project | Option" pathes. Package pathes.
  
• key words : Windows Environment Variables, PATH, Rsvars.bat, registry, Tools Environment Variables, Tools Options Library, Browsing Path, Project Options, Search Path, Package
  
• software used : Windows XP Home, Delphi 6, Delphi XE7
  
• hardware used : Pentium 2.800Mhz, 512 M memory, 140 G hard disc
  
• scope : Delphi 1 to 8, Delphi 2005, to Delphi 2010, Delphi XE to Delphi XE8, Seatle, Berlin, Tokyo
  
• level : Delphi developer
  
• plan :
  
  • The many Delphi IDE pathes
    
  • The Windows Environment variable PATH
    
  • The Rsvars.Bat variables
    
  • The Windows Registry
    
  • Tools | Environment Variables
    
  • Tools | Options | Delphi Options | Library
    
  • Project | Options
    
  • Custom path parameters
    
  • Delphi Pathes Summary
    
  • Download the Sources
    

1 - The many Delphi IDE pathes

Delphi uses several pathes:

• the Windows environment variables
  
• the Registry pathes
  
• the RSVARS.BAT definitions
  
• the Tools | Options pathes
  
• the Project | Options pathes
  
• the .dpr pathes
  

2 - The Windows Environment Variable PATH

We use a simple utility to display the environment variables:

We split the Path variable in the individual pathes:

and

• we hilighted the Xe7 pathes
  
• there are also Xe8 pathes, Xe3 pathes and Delphi 6 pathes
  
• there are Android pathes we used for direct android compilations
  

3 - The Rsvars.Bat variables

Here is the content of our Delphi Xe7 rsvars.bat file:

and if we display each path of PATH in its own directory, we have

and replacing each parameter by its value

Note that

• in our Delphi Xe7 version we have no %rameworkSDKDir% (we had not the Mobile Studio installed)
  
• the last %PATH% is a placeholder for the Windows PATH value (the "SET PATH" being the cmd.exe command which dynamically modifies the value of the Windows PATH environment variable, concatenating at the end the current in-memory PATH value)
  

4 - The Windows Registry

Here is a partial view of the Delphi Xe7 registry:

For our DCC build tools, we created a unit which analyzes our Delphi registry pathes (we only analyzed Delphi 5, Delphi 6, Delphi Xe2, Delphi Xe7 and Berlin).

Here is the display of the Xe7 registry :

Please note:

• some variables are not defined in rsvars.bat: BDSLIB and BDSUSERDIR. Those are defined by the IDE itself
  • BDSLIB is BDS plus "\Lib"
    
  • BDSUSERDIR is your user dir plus "Embarcadero\Studio\15.0"
    

5 - Tools | Options | Library

5.1 - Tools | Environment Variables

and

• the top part is computed by the IDE using the Window registry and IDE's own computations. For instance,
  • BDSLIB is defined as c:\program files\embarcadero\studio\15.0\lib
    
  • BDSUSERDIR is defined as C:\Documents and Settings\Felix\Mes documents\Embarcadero\Studio\15.0
    
• we cannot delete any of those variables
  
• we can override some of those values by selecting an item and clicking "add override"
  
• the bottom part are "user overrides". Here are the overrides of the system variables or new variables. Some of those "user" variables are already defined by the IDE
  

5.2 - Tools | Options | Delphi Options | Library>

5.2.1 - Selecting the Platform

At the top of this dialog, we first select the target for which we want to display the pathes. In our case the ""32-bit Windows" platform is selected

5.2.2 - Library Path :

For the selected Win 32 platform, the detailed content of our list is:

And

• the items come from the Windows Registry
  
• the first row is always $(BDSLIB)\$(Platform)\release
  
  • As explained $(BDSLIB) is BDS+ "\Lib".
    
  • $(Platform) will be the platform selected in the project manager for some project. For instance, we selected Win 32
    
  In our case

  

  so $(BDSLIB)\$(Platform)\release will be resolved as

    c:\Program Files\Embarcadero\Studio\15.0\LIB\Win32\release

  

• $(BDSUSERDIR)\Imports will resolve to

    C:\Documents and Settings\Felix\Mes documents\Embarcadero\Studio\15.0\Imports

  will depend on the current user. In our case

• $(BDSCOMMONDIR)\Dcp will resolve to

    C:\Documents and Settings\All Users\Documents\Embarcadero\Studio\15.0\Dcp
  

So if you installed DevExpress Vcl (223 packages !) or Jedi Jvcl (271 packages, 264 .DCUs) it certainly will speed up your compilation if you let the compiler include the .DCU instead of compiling the .PAS

IMPORTANT, note that

• since the first two entries ($(BDSLIB)\$(Platform)\release and $(BDSUSERDIR)\Imports) cannot be resolved for all platforms and users, those two items are ALWAYS grayed.
  The items will be resolved at compile time. And they are very important.

  Therefore NEVER click "Delete Invalid Pathes"

  Should this happen, add those items back using the values presented here
  

5.2.3 - The Browsing Path

So basically it contains the pathes of

• the Delphi source\
  
• some components sources (FDastReport, Madshi, Jedi)
  

Those pathes are mainly used by the Delphi editor, to be able to load the text of some unit by simply using Ctrl Click on the unit name or some identifier

5.2.4 - Debug DCU Path

6 - Project | Options

6.1 - How to include a unit

• saving it in the .DPR (.DPK) path
  
• adding it to the project .DPR
  
• specifying the Search Path in the "Project | Options"
  
• specifying the Library Path / Browsing Path
  

Let's start a first VCL project

	"File | New | Vcl Forms Application"
	save the DPR as p_project_1.dpr, u_main.pas in some pathes_demo\project_1\  path
	add some unit "File | New | Delphi Unit" and save it as u_calc.pas in a units\  sub directory
	compile everything
	the .EXE and the .DCU are save in a win32\debug\  subdirectory of the .DPR path:
	since we want to reuse the specify the .Exe and .DCU pathes: "Project | Options | Delphi Compiler | Output Directory" The default is   .$(Platform)$(Config) In our case for the Win32 platform in debug mode, it would be a the Win32\debug\  subdirectory of the .DPR folder Recompile Change the following values replace the "Output Directory" in "..\_exe" replace the "Unit Output Directory" in "_exe\_dcu"
	the .DCUs are now all in the _exe\dcu\  folder

Now let's create another project, project_2, which will use the u_calc unit:

	"File | New | Vcl Forms Application"
	save the DPR as p_project_2.dpr, u_main.pas in some pathes_demo\project_2\  path
	the main unit will contain Uses u_calc
	compile
	the compiler cannot find the u_calc unit:   [dcc32 Fatal Error] u_main_2.pas(21): F1026 File not found: 'C:programsusidepathes_demoproject_2u_calc.dcu'

6.1.1 - Copying u_calc in the .DPR project

6.1.2 - Including the u_calc in the .DPR

	"Project | Add to Project" then navigate to the project_1\units\  folder and select u_calc.pas
	compile

Please note that

• the path has nicely been compile as a relative path
  
• we could also manually add lines to add other units (possibly using some utility to automate this process), and then could use absolute path.
  
• if we move or rename the units or the pathes, we must make sure that those .DPR additions are still valid.
  

Therefore it is easier to somehow tell the IDE where it can find the relevant units without having to implicitely include them in the .DPR. Hence the "Project Option | Search Pathes" or "Tools | Options | Library"

6.1.3 - The Project | Options | Search Pathes

	remove the u_calc inclusion in the project either delete the "u_calc in '..project_1unitsu_calc.pas'" part of the .DPR or "Project Manager | u_calc.pas | Remove From Project" and confirm
	add a search path : "Project | Options | Delphi Compiler | Search Pathes | ellipsis | Browse | navigate and select u_calc | Add"
	click "Ok" and compile

Note that

• using the "ellipsis" to include the path will add an absolute path. You can modify this path into a relative path, but you have to compute it manually
  
• make sure there is no conflict between the units included in the "Search Pathes" and those directly included in the .DPR (in case of several units with the same name in different pathes or in case of change of unit name / path names)
  
• we added a Search Path only for Win 32 in debug mode. This is specified in the top level combobox of the "Project Option | Delphi Compiler" dialog

  We could place the include at some other target / debug level by selecting another level :

  

  In general, we start including at the highest level ("all configurations") and then override or add when required for the more specific level ("32 bit Windows Platform" for instance)
  

• the units are not displayed in the Project Manager treeview. You still can open a unit by "Ctrl Click" on the unit in some Uses list, or by "Ctrl Click" on some of the Unit's identifiers
  
• the search pathes apply to this project only.
  

6.1.4 - Project | Options | Search Pathes for dcu

	remove the .DPR inclusion of u_calc, and remove any Search Path
	"Project | Options | Delphi Compiler | Search Pathes" and add .._exedcu
	compile

	in the main unit, select u_calc and perform "Ctrl Click"
	the Editor cannot find the unit: "unable to locate file u_calc.pas"
	add a button which calls a method of the u_calc unit
	place a breakpoint on the calling statement
	run, click the button, hit F7 when the execution reaches the breakpoint
	the debugger cannot find the source:

6.1.5 - The Tools | Options | Library

	remove the .DPR inclusion of u_calc, and remove any Search Path
	add a library path: "Tools | Options | Library Path | ellipsis | navigate and add the dcu path"
	compile

	in the main unit, select u_calc and perform "Ctrl Click"
	the Editor cannot find the unit: "unable to locate file u_calc.pas"
	add a button which calls a method of the u_calc unit
	place a breakpoint on the calling statement
	run, click the button, hit F7 when the execution reaches the breakpoint
	the debugger cannot find the source:

6.1.6 - Tools | Options | Browsing Path

• either add the unit's path to "Project | Options | Delphi Compiler | Search Pathes"
  
• add the unit's path to "Tools | Options | BROWSING PATH"
  

	remove the .DPR inclusion of u_calc, and remove any Search Path
	add a browse path: "Tools | Options | Browsing Path | ellipsis | navigate and add the u_calc.pas path"
	compile load u_calc by "Ctrl Clic" on u_calc in the Uses u_calc; clause set a breakpoint on the call of an u_calc.pas Unit

• adding the .pas path to the "Tools | Options | Browsing Path" does not allow the compiler to find the u_calc.pas (F1026 File not found) (whereas the "Project | Options | Delphi Compiler | Search Pathes" did allow both compilation, loading with "Ctrl Click" and debugging). To compile, the "Tools | Options | Library Path" must specify where the u_calc.dcu is located
  

7 - Custom path parameters

• either in the Windows Environment Variables
  
• or in "Tools | Options | Environment Variables"
  

	create a "pathes_demo\project_1\units2\ " path
	place some u_compute.pas unit in this folder
	create a variable for "..project_1" in Delphi : "Tools | Options | Environment Variables | New"
	type "calc" and "..project_1"

	create a new project
	add a USES u_compute; to the main Unit
	add the Search Path using the environment variable
	compile load u_compile by "Ctrl Clic" on u_calc in the Uses u_calc; clause set a breakpoint on the call of an u_compute.pas Unit

8 - Delphi Pathes Summary

8.1 - Finding units

• the Compile can compile a Unit if
  
  • the .PAS is in the .DPR folder
    
  • the .PAS is include in the .DPR file
    
  • the .PAS is in a path included in "Project | Options | Delphi Compiler | Search Pathes"
    
  • the .DCU is in a path included in "Project | Options | Delphi Compiler | Search Pathes"
    
  • the .DCU is in a pas included in "Tools | Options | Library Path"
    
• the Editor can load a .PAS by using "Ctrl Click" on the unit name listed in a Uses clause or an identifier of the Interface of this Unit, and the debugger will load the unit if
  • the .PAS is in the .DPR folder
    
  • the .PAS is include in the .DPR file
    
  • the .PAS is in a path included in "Project | Options | Delphi Compiler | Search Pathes"
    
  • the .PAS is in a path included in "Tools | Options | Browsing Path"
    

8.2 - Where to place the DCU's

For the post Xe versions, we potentially have 7 platfoms, and 2 variants (debug and release). Using the "Project | Options", we could specify 14 dcu pathes !

We always used a separate path to group all DCUs of project families. We often migrate projects for Win 32 and Win 64. Keeping a single DCU path forces the recompilation of all DCUs, including the packages. Therefore we routinely use 2 locations for those projects. However we do not separate debug and release (when the code does not contain different compiling options or $IFDEFs for debug and release).

8.3 - Compiling Packages

To avoid this, the best solution is

• to add the package's .DCU path(es) in "Tools | Options | Library | Library Path"
  
• if you want to be able to load and debug the package's .PAS, add the .PAS path(es) in "Tools | Options | Library | Browsing Path"
  

8.4 - Default Project Path

8.5 - Nevertheless

• F1026 File not found
  
• F2039 Could not create output file
  

9 - Download the Sources

• zip_d6_environment_rsvars_registry.zip: display the environment variables, the RSVARS.BAT file, the Delphi registry pathes (45 K, Delphi 6)
  
• pathes_demo.zip: the 7 projects used for this presentation (452 K, Xe7)
  

• the main program (.DPR, .DOF, .RES), the main form (.PAS, .DFM), and any other auxiliary form
  
• any .TXT for parameters, samples, test data
  
• all units (.PAS) for units
  

• are self-contained: you will not need any other product (unless expressly mentioned).
  
• for Delphi 6 projects, can be used from any folder (the pathes are RELATIVE)
  
• will not modify your PC in any way beyond the path where you placed the .ZIP (no registry changes, no path creation etc).
  

• create or select any folder of your choice
  
• unzip the downloaded file
  
• using Delphi, compile and execute
  

The Pascal code uses the Alsacian notation, which prefixes identifier by program area: K_onstant, T_ype, G_lobal, L_ocal, P_arametre, F_unction, C_lass etc. This notation is presented in the Alsacian Notation paper.

As usual:

• please tell us at fcolibri@felix-colibri.com if you found some errors, mistakes, bugs, broken links or had some problem downloading the file. Resulting corrections will be helpful for other readers
  
• we welcome any comment, criticism, enhancement, other sources or reference suggestion. Just send an e-mail to fcolibri@felix-colibri.com.
  
• or more simply, enter your (anonymous or with your e-mail if you want an answer) comments below and clic the "send" button

  Name :
  E-mail :
  Comments * :

• and if you liked this article, talk about this site to your fellow developpers, add a link to your links page ou mention our articles in your blog or newsgroup posts when relevant. That's the way we operate: the more traffic and Google references we get, the more articles we will write.
  

• StackOverflow, about the Delphi compilation order
  
• The Garbled PATH Variable : about the PATH variable, with a utility factoring some common part of the pathes in order to shorten the PATH length
  

10 - The author